<html>
<!-- (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008, 2009 Hewlett-Packard Development Company, LP -->
<head>
<title>Jena2 MySQL HowTo</title>
<link href="../styles/doc.css" rel="stylesheet" type="text/css" />
</head>
<body>

<h1>HowTo Use MySQL Database System with Jena2</h1>

<h2>What is MySQL?</h2>

<p><a href="http://www.mysql.com/">MySQL</a> is an open-source SQL database system available without fee under GPL 
(Gnu General Public License). It combines good performance with a wide feature 
set and comes in a variety of configurations to support difference application 
requirements. See <a href="http://www.mysql.com/">http://www.mysql.com/</a> for 
more information. When using InnoDB tables, Jena provides full ACID transaction 
support.</p>

<h2>Download and Installation of MySQL</h2>

<p>MySQL software and the JDBC driver may be downloaded from
<a href="http://www.mysql.com/downloads/">http://www.mysql.com/downloads/</a>. 
The JDBC driver is available from the same Web page (see MySQL Connector/J). (If these links are not 
found, go to the MySQL home page and search for downloads for the latest version 
of the server and JDBC driver.)</p>
<h2>Connecting Your Jena Program to MySQL</h2>

<p>Jena supports both memory models and database models. In general, a Jena program 
may use both types of models identically. However, there are some differences 
in how the models are created. Creating a memory model can be done with a single 
Jena call. Creating a database model, or opening a previously created one, 
requires several steps as as follows.</p>
<p>Persistent models are <a href="creating-db-models.html">created</a> in the 
same way for any database system: </p>
<blockquote>
  <ol>
    <li>Load the JDBC driver. This enables the Jena program to communicate with 
    the database instance.</li>
    <li>Create a database connection. This creates a Java object for a database 
    connection.</li>
    <li>Create a ModelMaker for the database</li>
    <li>Create a Model for existing or new data.</li>
  </ol>
</blockquote>

<p>These steps are illustrated in the following Java code.</p>

<pre class="box">
String className = &quot;<font face="Courier New" SIZE="2">com.mysql.jdbc.Driver</font>&quot;;         // path of driver class
Class.forName (className);                          // Load the Driver
String DB_URL =     &quot;<font face="Courier New" SIZE="2">jdbc:mysql://localhost/test</font>&quot;;  // URL of database 
String DB_USER =   &quot;????&quot;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;     // database user id
String DB_PASSWD = &quot;????&quot;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;      // database password
String DB =&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &quot;<font face="Courier New" SIZE="2">MySQL</font>&quot;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;      // database type

// Create database connection
IDBConnection conn = new DBConnection ( DB_URL, DB_USER, DB_PASSWD, DB );
ModelMaker maker = ModelFactory.createModelRDBMaker(conn) ;

// create or open the default model
Model model = maker.createDefaultModel();

// Close the database connection
conn.close();
</pre>
    
<h2>Notes</h2>

<p>Jena stores all models in a single database using whatever database (name) specified on the database connection. See the <a href="index.html">Jena Database Release Notes</a> for 
details on the physical layout.</p>
<h3>MySQL and character sets</h3>
<p>To handle the full range of characters, you can use the
<a href="http://en.wikipedia.org/wiki/UTF-8">UTF-8</a> character set: in the 
server configuration file:</p>
<pre>default-character-set=utf8</pre>
<p>Note: the character set name must be exactly &quot;utf8&quot;.&nbsp; It must not be 
&quot;utf-8&quot; (an alias name) - the server will not start if the character set name is 
wrong.</p>
<p>Alternatively, if the server needs to run with some other character set, 
create the database as a UTF-8 database and force the JDBC driver to use Unicode 
regards of negotiation with the server:</p>
<p>Database creation:</p>
<pre>create database <i>jenatest</i> character set utf8 ;</pre>
<p>JDBC URL arguments:</p>
<pre>?useUnicode=yes&amp;characterEncoding=utf8</pre>

<h3>MySQL Driver issues</h3>
<ul>
  <li>Drivers from the 3.0 and 3.1 series work with Jena 2.4 and later.</li>
  <li>Drivers from the 3.1.* series do not work with Jena before Jena version 
  2.4</li>
  <li>The 5.0.0-beta driver is unreliable due to a concurrency bug in the JDBC 
  driver.</li>
</ul>

<p>The situations where the 5.0.0-beta will deadlock are rare.&nbsp; The 
5.0.0-beta driver can be used by setting &quot;Query Only Asserted&quot; (see
<a href="options.html">options</a>).</p>
<p>&nbsp;</p>

<p>&nbsp;</p>

</body>
</html>
